home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / Td.man < prev    next >
Text File  |  1990-03-30  |  24KB  |  531 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/c/etc/RCS/Td.man,v 1.5 90/03/30 15:45:44 brent Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS Td lib
  13. .BS
  14. '\" Note:  do not modify the .SH NAME line immediately below!
  15. .SH NAME
  16. Td_Create, Td_Delete, Td_PutRaw, Td_GetRaw, Td_ControlRaw,
  17. Td_Open, Td_Close, Td_PutCooked, Td_GetCooked,
  18. Td_ControlCooked, Td_CreatePdev,
  19. Td_DeletePdev \- Terminal driver implementing 4.3 BSD operations.
  20. .SH SYNOPSIS
  21. .nf
  22. \fB#include <td.h>\fR
  23. .sp
  24. Td_Terminal
  25. \fBTd_Create\fR(\fIbufferSize\fR, \fIcookedProc\fR, \fIcookedData\fR, \fIrawProc\fR, \fIrawData\fR)
  26. .sp
  27. \fBTd_Delete\fR(\fIterminal\fR)
  28. .sp
  29. \fBTd_PutRaw\fR(\fIterminal\fR, \fInumBytes\fR, \fIbuffer\fR)
  30. .sp
  31. int
  32. \fBTd_GetRaw\fR(\fIterminal\fR, \fInumBytes\fR, \fIbuffer\fR)
  33. .sp
  34. \fBTd_ControlRaw\fR(\fIterminal\fR, \fIoperation\fR)
  35. .sp
  36. int
  37. \fBTd_Open\fR(\fIterminal\fR, \fIselectBitsPtr\fR)
  38. .sp
  39. \fBTd_Close\fR(\fIterminal\fR)
  40. .sp
  41. int
  42. \fBTd_PutCooked\fR(\fIterminal\fR, \fInumBytesPtr\fR, \fIbuffer\fR, \fIsigNumPtr\fR, \fIselectBitsPtr\fR)
  43. .sp
  44. int
  45. \fBTd_GetCooked\fR(\fIterminal\fR, \fIpID\fR, \fIfamilyID\fR, \fInumBytesPtr\fR, \fIbuffer\fR, \fIsigNumPtr\fR, \fIselectBitsPtr\fR)
  46. .sp
  47. int
  48. \fBTd_ControlCooked\fR(\fIterminal\fR, \fIcommand\fR, \fIformat\fR, \fIinputSize\fR, \fIinput\fR, \fIoutputSizePtr\fR, \fIoutput\fR, \fIsigNumPtr\fR, \fIselectBitsPtr\fR)
  49. .sp
  50. Td_Pdev
  51. \fBTd_CreatePdev\fR(\fIname\fR, \fIrealNamePtr\fR, \fItermPtr\fR, \fIrawProc\fR, \fIrawData\fR)
  52. .sp
  53. \fBTd_DeletePdev\fR(\fIttyPdev\fR)
  54. .SH ARGUMENTS
  55. .AS Td_Terminal (*cookedProc)()
  56. .AP int bufferSize in
  57. Size of output buffer to use for terminal.  This is not an exact
  58. specification, in that the terminal driver may actually allow more
  59. characters than this to be buffered, but it will always allow at
  60. least this many characters to be buffered.
  61. .AP int (*cookedProc)() in
  62. Procedure to call for control operations on cooked side of driver.
  63. .AP ClientData cookedData in
  64. Additional value to pass to \fIcookedProc\fR.
  65. .AP int (*rawProc)() in
  66. Procedure to call for control operations on raw side of driver.
  67. .AP ClientData rawData in
  68. Additional value to pass to \fIrawProc\fR.
  69. .AP Td_Terminal terminal in
  70. Token for terminal;  must have been returned by some previous call
  71. to \fBTd_Create\fR.
  72. .AP int numBytes in
  73. Total number of bytes to get or put for/from raw side of terminal.
  74. .AP char *buffer in/out
  75. Buffer containing characters to be written, or containing space in
  76. which to place characters being read.
  77. .AP int operation in
  78. Control operation being invoked from raw side of terminal.  Currently
  79. no operations are defined.
  80. .AP int *selectBitsPtr in/out
  81. Points to word whose bits (\fBFS_READABLE\fR and \fBFS_WRITABLE\fR)
  82. indicate whether read or write operations can complete
  83. successfully.  Different procedures may modify either or both of
  84. these bits.
  85. .AP int *numBytesPtr in/out
  86. Points to maximum number of bytes to read or write.  Gets overwritten
  87. with actual number of bytes read or written.
  88. .AP int *sigNumPtr out
  89. Overwritten with signal number to apply to invoking process.  Zero
  90. means no signal.
  91. .AP int pID in
  92. Identifier of process invoking operation.
  93. .AP int familyID in
  94. Process group that \fIpID\fR belongs to.
  95. .AP int command in
  96. Number of IOControl operation.  Note:  these are Sprite IOControl
  97. numbers, not UNIX ioctl numbers.  See \fB<dev/tty.h>\fR for definitions.
  98. .AP Fmt_Format format in
  99. Byte ordering and alignment format for the buffers used in an IOControl.
  100. Usually the constant \fBFMT_MY_FORMAT\fP can be passed in for this parameter.
  101. .AP int inputSize in
  102. Number of bytes of information in \fIinput\fR
  103. .AP char *input in
  104. Input buffer for IOControl operation.  Its structure depends on the
  105. IOControl.
  106. .AP int *outputSizePtr in/out
  107. Points to word specifiying total number of bytes of output buffer
  108. space available at \fIoutput\fR.  Modified to hold
  109. the actual number of output bytes provided by the IOControl.
  110. .AP char *output in
  111. Output buffer for IOControl operation.  Its structure depends on the
  112. IOControl.
  113. .AP char *name in
  114. Name of file to use for terminal pseudo-device.  May be either full
  115. name or root.
  116. .AP char **realNamePtr out
  117. Where to store actual name of terminal pseudo-device used.  NULL means
  118. \fIname\fR is a root;  non-NULL means \fIname\fR is the full path
  119. name.
  120. .AP Td_Terminal *termPtr out
  121. If non-NULL, token for terminal gets stored in the word pointed to
  122. by \fItermPtr\fR.
  123. .AP Td_Pdev ttyPdev in
  124. Token for terminal-driven pseudo-device to destroy.  Must have been
  125. returned previously by \fBTd_CreatePdev\fR.
  126. .BE
  127.  
  128. .SH INTRODUCTION
  129. .PP
  130. The Td library procedures implement a terminal driver with
  131. the same features as the terminal driver implemented in the 4.3 BSD
  132. kernel.  The data structures managed
  133. by the Td library are called Td_Terminals and have
  134. two interfaces:  cooked and raw.  The raw interface is used to
  135. communicate between the Td procedures and the low-level device
  136. corresponding to the terminal (usually a serial line device
  137. or a window on a screen).  The cooked interface is used to communicate
  138. with processes accessing the 4.3-BSD-like terminal.  In between, the
  139. Td library provides input and output character buffering, echoing
  140. and line editing, flow control, interrupt characters, and all the other
  141. features of the 4.3 BSD terminal driver.
  142. .PP
  143. Each of the cooked and raw interfaces has at least four procedures associated
  144. with it.  Three of the procedures are provided by Td:  one to pass
  145. characters into the terminal driver (e.g. a character that was just
  146. typed on the keyboard, or a character that a user process wishes
  147. to ouput on the terminal), one to extract characters from
  148. the terminal driver (e.g. to pass them to a waiting user process, or
  149. to output them onto the terminal), and one to invoke control operations
  150. on the terminal.  The fourth procedure for each interface is provided
  151. by the program in which Td is embedded.  These procedures are called
  152. back by Td to notify the program of various events, for example, that
  153. characters are waiting in the terminal's output buffer, or that a
  154. full line is present in the terminal's input buffer.
  155. .PP
  156. Most of the procedures in the Td library are generic in
  157. that they can be used in many different situations, including both
  158. user programs and the Sprite kernel.  Two additional procedures,
  159. \fBTd_CreatePdev\fR and \fBTd_DeletePdev\fR are provided to connect
  160. the cooked side of a Td_Terminal to a pseudo-device.  These procedures
  161. are used by user-level Sprite programs like \fBrlogind\fR
  162. and window-based terminal emulators.
  163.  
  164. .SH "CREATING AND DELETING TERMINALS"
  165. .PP
  166. The \fBTd_Create\fR procedure is used to create a Td_Terminal.  It
  167. returns a token that must be passed to most of the other Td procedures.
  168. Several Td_Terminals may exist at the same time, each created by a
  169. separate call to \fBTd_Create\fR.  Each Td_Terminal corresponds to
  170. one logical terminal with its own input and output buffers.  The
  171. \fIcookedProc\fR and \fIrawProc\fR procedures, and their associated
  172. ClientData values, are used to invoke control operations on the two
  173. sides of the terminal.  The use of these two procedures
  174. is described in the sections below.  The \fIbufferSize\fR argument
  175. is described in the \fBBUFFERING\fR section below.
  176. .PP
  177. \fBTd_Delete\fR simulates a hangup on a Td_Terminal,
  178. then destroys all of the state associated with the terminal.
  179. After it is called, the \fIterminal\fR argument should never be used
  180. again by the caller.
  181.  
  182. .SH "RAW INTERFACE"
  183. .PP
  184. The raw interface is used to communicate between the terminal driver
  185. and the ``dumb'' terminal device.  It consists of the three procedures
  186. \fBTd_PutRaw\fR, \fBTd_GetRaw\fR, \fBTd_ControlRaw\fR, and the
  187. \fIrawProc\fR procedure passed to \fBTd_Create\fR.
  188. .PP
  189. When characters are typed on the keyboard associated with the raw terminal,
  190. they should be passed to the temrinal driver by calling \fBTd_PutRaw\fR.
  191. The Td library will then perform input processing such as echoing and
  192. line editing.
  193. .PP
  194. The procedure \fBTd_GetRaw\fR should be invoked to remove characters
  195. from the terminal's output buffer and copy them to \fIbuffer\fR.
  196. The return value indicates how many characters were actually copied,
  197. up to either \fInumBytes\fR or the total number of characters in
  198. the output buffer.  The return value is zero if the output buffer
  199. is empty.  The caller of \fBTd_GetRaw\fR should then pass the characters
  200. to the raw serial device, or display them on the screen if the terminal
  201. is being emulated in a window.  Note that it is up to the application
  202. in which Td is embedded to decide when to call \fBTd_GetRaw\fR.  However,
  203. Td calls \fIrawProc\fR to notify the application that the terminal's
  204. output buffer contains characters;  see below for details.
  205. .PP
  206. The procedure \fBTd_ControlRaw\fR should be called when certain
  207. interesting events occur on the raw terminal.  The \fIoperation\fR
  208. argument identifies the event that occurred, and must be one of:
  209. .RS
  210. .IP \fBTD_BREAK\fR 20
  211. Means that a break just occurred on the raw device.  \fBTd_ControlRaw\fR
  212. should only be called when the break condition ends.
  213. .IP \fBTD_GOT_CARRIER\fR 20
  214. Means that there is now carrier present on the raw device (e.g. a
  215. modem connection was just made).
  216. .IP \fBTD_LOST_CARRIER\fR 20
  217. Means that carrier just went away on the raw device (e.g. the party
  218. on the other end hung up the phone).
  219. .RE
  220. .PP
  221. The Td module will invoke the procedure \fIrawProc\fR, which was
  222. passed to \fBTd_Create\fR, to ask for special actions on the raw terminal
  223. device, or to provide additional information that may be useful in
  224. managing the raw terminal device.  \fIRawProc\fR must have the
  225. following structure:
  226. .DS
  227. \fCint
  228. rawProc(rawData, operation, inputSize, input, outputSize, output)
  229.     ClientData rawData;
  230.     int operation;
  231.     int inputSize;
  232.     char *input;
  233.     int outputSize;
  234.     char *output;
  235. {
  236.  ...
  237. }\fR
  238. .DE
  239. The \fIrawData\fR argument will be the same as the \fIrawData\fR
  240. argument passed to \fBTd_Create\fR.  It usually refers to a data structure
  241. describing the raw device, which will be used by \fIrawProc\fR.  The
  242. \fIoperation\fR parameter gives the reason for the call, the \fIinputSize\fR
  243. and \fIinput\fR arguments describe an area of data that Td is making
  244. available to \fIrawProc\fR, and \fIoutputSize\fR and \fIoutput\fR
  245. describe a buffer in which \fIrawProc\fR may place data that it wishes
  246. to return to Td.  The return value from \fIrawProc\fR indicates how many
  247. bytes of data were actually placed at \fIoutput\fR;  it must not be
  248. greater than \fIouptutSize\fR.  At present, \fIoperation\fR must be
  249. one of the following:
  250. .RS
  251. .IP \fBTD_RAW_START_BREAK\fR 30
  252. Initiate a break condition on the raw device, if the device supports it.
  253. There is no input data or output data for this operation.
  254. .IP \fBTD_RAW_STOP_BREAK\fR 30
  255. End a break condition on the raw device, if the device supports it.
  256. There is no input data or output data for this operation.
  257. .IP \fBTD_RAW_SET_DTR\fR 30
  258. Set the ``data terminal ready'' condition on the raw device, if
  259. it supports such an operation.
  260. There is no input data or output data for this operation.
  261. .IP \fBTD_RAW_CLEAR_DTR\fR 30
  262. Clear the ``data terminal ready'' condition on the raw device, if
  263. it supports such an operation.
  264. There is no input data or output data for this operation.
  265. .IP \fBTD_RAW_SHUTDOWN\fR 30
  266. The terminal has been closed and is being shut down.  The raw
  267. device should now be shut down too (e.g. hang up a modem).
  268. There is no input data or output data for this operation.
  269. .IP \fBTD_RAW_OUTPUT_READY\fR 30
  270. This operation indicates that the output buffer for the terminal
  271. has just become non-empty.  At some point in the future, the application
  272. should invoke \fBTd_GetRaw\fR and output the characters to the device.
  273. There is no input data or output data for this operation.
  274. .IP \fBTD_RAW_FLUSH_OUTPUT\fR 30
  275. If there are any characters buffered for output on the raw device
  276. but not yet output, they should be discarded without outputting them.
  277. There is no input data or output data for this operation.
  278. .IP \fBTD_RAW_FLOW_CHARS\fR 30
  279. The flow-control characters for the terminal have just been modified.
  280. The \fIinput\fR argument points to a structure with the following
  281. format:
  282. .DS
  283. .ta 4c
  284. \fCtypedef struct {
  285.     char stop;
  286.     char start;
  287. } Td_FlowChars;\fR
  288. .DE
  289. .IP
  290. Whenever \fIstop\fR is received from the raw terminal, output should
  291. be stopped until \fIstart\fR is received.  \fIStop\fR and \fIstart\fR
  292. may be the same character.
  293. This call is made so that the driver for the raw device may implement
  294. flow control directly in order to provide faster response to the
  295. \fIstart\fR and \fIstop\fR characters.  The raw device driver may
  296. ignore these calls and simply pass the flow control characters to
  297. the terminal driver, in which case Td will implement flow control,
  298. albeit with slower response.  If either \fIstop\fR or \fIstart\fR
  299. is -1, then the raw driver must not implement flow control.  There is
  300. no output data for this operation.
  301. .IP \fBTD_RAW_SET_BAUD_RATE\fR 30
  302. Someone has just asked to change the baud rate for the device.  Both the
  303. \fIinput\fR and \fIoutput\fR arguments point to structures with the
  304. following format:
  305. .DS
  306. .ta 4c
  307. \fCtypedef struct {
  308.     char ispeed;
  309.     char ospeed;
  310. } Td_BaudRate;\fR
  311. .DE
  312. .IP
  313. The \fBispeed\fR and \fBospeed\fR fields have the same values as
  314. they would in an \fBsgttyb\fR structure, such as \fBB9600\fR.  The
  315. \fIinput\fR argument gives the requested baud rates.  \fIRawProc\fR
  316. may either accept these speeds or override them and return the
  317. actual speeds it used in the \fIoutput\fR area.  If the \fIinput\fR
  318. speeds are accepted, then \fIrawProc\fR need not modify the \fIoutput\fR
  319. area;  it can simply return 0.
  320. .IP \fBTD_RAW_GET_BAUD_RATE\fR 30
  321. This operation is invoked to fetch the current input and output speeds
  322. for the raw device.  There is no \fIinput\fR area, but \fIoutput\fR
  323. refers to a \fBTd_BaudRate\fR structure as described above for
  324. \fBTD_RAW_SET_BAUD_RATE\fR.  \fIRawProc\fR should fill in the current
  325. speeds for the device at \fI*output\fR and return \fBsizeof(Td_BaudRate)\fR.
  326. .RE
  327.  
  328. .SH "COOKED INTERFACE"
  329. .PP
  330. The cooked interface is used to communicate between the terminal
  331. driver and the processes wishing to access a device with full
  332. 4.3 BSD terminal semantics.  As with the raw interface, it consists
  333. of a collection of Td procedures that the enclosing application
  334. invokes, plus one procedure in the enclosing application that
  335. Td invokes.
  336. .PP
  337. Whenever a process attempts to open the terminal device, the
  338. procedure \fBTd_Open\fR should be called.  If the terminal is
  339. in ``exclusive'' mode (meaning opens are being refused), then
  340. a UNIX error number is returned.  Otherwise zero is returned and
  341. the \fBFS_READABLE\fR and \fBFS_WRITABLE\fR bits of
  342. \fI*selectBitsPtr\fR are set to indicate whether there are input
  343. characters or output buffer space available, respectively.
  344. .PP
  345. When the terminal is closed, \fBTd_Close\fR should be invoked.
  346. There should be exactly one \fBTd_Close\fR call for each \fBTd_Open\fR
  347. call:  if an open stream is \fBdup\fR-ed, \fBTd_Close\fR shouldn't
  348. be called until the last \fBdup\fR-ed copy is closed.
  349. .PP
  350. When a process writes data to the cooked terminal, \fBTd_PutCooked\fR
  351. should be invoked to pass the data to the terminal driver.  The
  352. characters will be added to the terminal's output buffer after
  353. performing output processing on them.  The return value is always
  354. zero (meaning that the characters are always accepted).  The
  355. \fBFS_WRITABLE\fR bit in \fI*selectBitsPtr\fR will be updated to reflect
  356. whether the terminal's output buffer is now ``full'' (see the
  357. \fBBUFFERING\fR section below for more on what this means).  If so, then
  358. no more calls should be made to \fBTd_PutCooked\fR until the terminal
  359. driver gives notice that there is more space in the output buffer
  360. (this is done by calling \fIcookedProc\fR as described below).
  361. \fBTd_PutCooked\fR overwrites the value at \fI*sigNumPtr\fR;  if
  362. the value written is non-zero then it is a UNIX signal number that should
  363. be applied to the calling process.
  364. .PP
  365. When a process wishes to read characters from the cooked terminal,
  366. \fBTd_GetCooked\fR should be called.  This procedure will remove characters
  367. from the terminal's input buffer (up to \fI*numBytesPtr\fR of them)
  368. and copy them to \fIbuffer\fR.  The
  369. value at \fI*numBytesPtr\fR will be updated to reflect the actual
  370. number of characters returned.  The return value from \fBTd_GetCooked\fR
  371. will normally be zero;  if an error occurred, then the return value
  372. will be a UNIX error number.  If the terminal's input buffer is empty,
  373. then the return value will be \fBEWOULDBLOCK\fR and \fI*numBytesPtr\fR
  374. will be set to zero.  The \fBFS_READABLE\fR bit of \fI*selectBitsPtr\fR
  375. will be updated to reflect whether there are still more characters ready in
  376. the terminal's input buffer.  \fBTd_PutCooked\fR overwrites the
  377. value at \fI*sigNumPtr\fR;  if
  378. the value written is non-zero then it is a UNIX signal number that should
  379. be applied to the calling process (this is used, for example, to
  380. generate \fBSIGTTIN\fR signals).
  381. .PP
  382. When a process invokes an IOControl operation on the terminal,
  383. \fBTd_ControlCooked\fR should be called.  The arguments to
  384. \fBTd_ControlCooked\fR indicate the IOControl number (\fIcommand\fR),
  385. plus an input buffer (\fIinputSize\fR and \fIinput\fR) and an
  386. output buffer (\fI*outputSizePtr\fR and \fIoutput\fR).  The
  387. value at \fI*outputSizePtr\fR will be modified to reflect the
  388. actualy number of bytes of output data written at \fIoutput\fR
  389. (this will be no more than the original value of \fI*outputSizePtr\fR).
  390. The contents of the input and output buffers are determined by the
  391. specific \fIcommand\fR being requested.  See the documentation on
  392. the 4.3 BSD terminal driver for details.
  393. The byte ordering and structure alignment of the input and output buffers
  394. is specified by the \fIformat\fP parameter.  The normal value to pass in
  395. is for \fIformat\fP is \fBFMT_MY_FORMAT\fP, which is defined in ``fmt.h''.
  396. \fBTd_ControlCooked\fR will
  397. reformat the input and output buffers, if necessary, to match the
  398. byte ordering of a remote client process.
  399. \fBTd_ControlCooked\fR
  400. will modify the \fBFS_READABLE\fR and \fBFS_WRITABLE\fR bits of
  401. \fI*selectBitsPtr\fR to reflect the state of the terminal's
  402. input and output buffers when the IOControl completes.
  403. \fBTd_PutCooked\fR overwrites the value at \fI*sigNumPtr\fR;  if
  404. the value written is non-zero then it is a UNIX signal number that should
  405. be applied to the calling process.
  406. .PP
  407. The Td library will invoke the \fIcookedProc\fR, which was passed
  408. as an argument to \fBTd_Create\fR, when it wishes to give notice
  409. of interesting events related to the cooked side of the terminal.
  410. \fICookedProc\fR should have the following structure:
  411. .DS
  412. \fCint
  413. cookedProc(cookedData, operation, inputSize, input, outputSize, output)
  414.     ClientData cookedData;
  415.     int operation;
  416.     int inputSize;
  417.     char *input;
  418.     int outputSize;
  419.     char *output;
  420. {
  421.  ...
  422. }\fR
  423. .DE
  424. The \fIcookedData\fR argument will be the same as the \fIcookedData\fR
  425. argument passed to \fBTd_Create\fR.  It usually refers to a data structure
  426. describing the interface to processes using the cooked terminal.
  427. The other arguments to \fIcookedProc\fR and its result
  428. have the same meaning as the arguments and result
  429. for \fIrawProc\fR, except that  \fIoperation\fR has different meanings.  The
  430. values currently defined for \fIoperation\fR are:
  431. .RS
  432. .IP \fBTD_COOKED_SIGNAL\fR 30
  433. A signal should be generated for the controlling process group
  434. associated with the terminal.  \fIInput\fR will point to a structure
  435. with the following format:
  436. .DS
  437. .ta 4c
  438. \fCtypedef struct {
  439.     int sigNum;
  440.     int groupID;
  441. } Td_Signal;\fR
  442. .DE
  443. .IP
  444. The \fIsigNum\fR field gives a UNIX signal number (e.g. \fBSIGINT\fR),
  445. and \fIgroupID\fR identifies the controlling process group for
  446. the terminal.  \fICookedProc\fR is not expected
  447. to return any output data.
  448. .IP \fBTD_COOKED_READS_OK\fR 30
  449. There is now readable data in the input buffer associated with the
  450. terminal, so that the next call to \fBTd_GetCooked\fR will not
  451. return \fBEWOULDBLOCK\fR.  If there is a waiting process, it should
  452. probably be woken up.  There is no input data or output data for
  453. this operation.
  454. .IP \fBTD_COOKED_WRITES_OK\fR 30
  455. The output buffer for the terminal is now empty.  If there is a process
  456. waiting to do output, it should probably be woken up.
  457. There is no input data or output data for this operation.
  458. .RE
  459.  
  460. .SH "PSEUDO-DEVICE INTERFACE"
  461. .PP
  462. The Td library also contains routines to connect the cooked side of
  463. a terminal to a pseudo-device.  The pseudo-device routines use the
  464. facilities of the Pdev library, which in turn requires that the
  465. application use the \fBFs_Select\fR library to manage I/O channels.
  466. The non-pseudo-device portions of the Td library may be used without
  467. also using \fBFs_Select\fR.
  468. .PP
  469. \fBTd_CreatePdev\fR creates a pseudo-device file and arranges for the
  470. file to have terminal-like behavior by associating it with a terminal
  471. managed by the Td library.  Once \fBTd_CreatePdev\fR has been called,
  472. the pseudo-device and the cooked side of its terminal will be managed
  473. automatically.  However, it is up to \fBTd_CreatePdev\fR's caller to manage
  474. the raw side of the pseudo-terminal.  The \fIrawProc\fR and \fIrawData\fR
  475. arguments to \fBTd_CreatePdev\fR are the same as the corresponding arguments
  476. to \fBTd_Create\fR (\fBTd_CreatePdev\fR passes them to \fBTd_Create\fR
  477. when it creates the terminal).  If the \fItermPtr\fR argument to
  478. \fBTd_CreatePdev\fR is not NULL, then \fBTd_CreatePdev\fR stores
  479. the Td_Terminal token for the pseudo-terminal at \fI*termPtr\fR; this
  480. allows the application to invoke procedures like \fBTd_PutRaw\fR.
  481. .PP
  482. The name of the pseudo-device file created by \fBTd_CreatePdev\fR
  483. may be specified in either of two ways.  If the \fIrealNamePtr\fR
  484. argument to \fBTd_CreatePdev\fR is NULL, then the \fIname\fR
  485. argument gives the complete name of the pseudo-device file.
  486. If \fIrealNamePtr\fR is not NULL, then the pseudo-device file will
  487. be created in a host-specific directory for the machine on which
  488. the program is running, and the file name will have the form
  489. \fInameXX\fR, where \fIXX\fR is a small integer chosen to avoid
  490. conflict with other files that have the same \fIname\fR.  A pointer
  491. to the complete name will be stored in \fI*realNamePtr\fR;  the
  492. storage for the name is allocated by \fBmalloc\fR and should eventually
  493. be freed by \fBTd_CreatePdev\fR's caller.
  494. .PP
  495. \fBTd_CreatePdev\fR normally returns a token for the pseudo-terminal.
  496. If the pseudo-device couldn't be opened, then NULL is
  497. returned and the variable \fBpdev_ErrorMsg\fR points to a string
  498. describing what went wrong.
  499. .PP
  500. The only use for the token returned by \fBTd_CreatePdev\fR
  501. is to pass it to \fBTd_DeletePdev\fR.
  502. When this happens, the pseudo-device is closed and the associated
  503. terminal is destroyed by calling \fBTd_Delete\fR.
  504.  
  505. .SH BUFFERING
  506. .PP
  507. The input buffer for a Td_Terminal grows automatically to accommodate
  508. as much data as is present:  there is no upper limit on its size.  The
  509. output buffer will also grow automatically:  \fBTd_PutCooked\fR
  510. always accepts all the data passed to it.  However, it is usually
  511. a bad idea to buffer a very large number of characters on output, since
  512. these characters will have to be output even if the process is killed
  513. with a control-C.  The \fIbufferSize\fR argument to \fBTd_Create\fR
  514. specifies a nominal output buffer size;  whenever more than this many
  515. characters are buffered, \fBTd_PutCooked\fR will turn off the
  516. \fBFS_WRITABLE\fR bit in \fI*selectBitsPtr\fR to indicate that the
  517. buffer is nominally full;  the enclosing application should then
  518. refuse to accept more characters for output (e.g., by suspending
  519. the process).  When the output buffer empties, \fIcookedProc\fR
  520. will be invoked with a \fBTD_COOKED_WRITES_OK\fR command.
  521.  
  522. .SH EXAMPLES
  523. .PP
  524. The best way to learn how to use the Td library is to look
  525. at examples in the Sprite source code.  The simplest example is the
  526. \fBmktty\fR program;  other examples are \fBrlogind\fR (the remote-login
  527. server) and \fBtx\fR (a window-based terminal emulator).
  528.  
  529. .SH KEYWORDS
  530. 4.3 BSD, pseudo-device, terminal driver
  531.